Skip to content

fix: show loading, error, and degraded states with retry (#10) - #22

Merged
GeoBradDev merged 25 commits into
mainfrom
issue-10-loading-error-degraded-states
Nov 8, 2026
Merged

GeoBradDev merged 25 commits into
mainfrom
issue-10-loading-error-degraded-states

Conversation

@GeoBradDev

Copy link
Copy Markdown
Owner

Summary

Failed or slow loads used to leave an empty map, the toggle still said ON, and the header always said SYS NOMINAL. Now the app reports its real state:

  • Layer panel status: each data layer (AIRPORTS, SEA PORTS) shows LOADING..., a count such as 72,690 FEATURES, or LOAD FAILED, with the error in the tooltip and a RETRY button (Retry Airports, Retry Sea Ports). Retry refetches without a page reload and moves focus to the layer checkbox, so focus is never dropped. useAirports and usePorts gain a stable retry and work with today's fetch, so the Airports layer downloads a 12.7 MB unpinned third-party CSV and parses it on the main thread #9 pipeline work is not affected.
  • Heatmap: the HEATMAP row appears whenever WebGPU is present and shows AWAITING AIRPORTS, NO AIRPORT DATA, COMPUTING..., READY, or COMPUTE FAILED with Retry Heatmap. useGPUHeatmap now wraps the compute in pushErrorScope('validation') and pushErrorScope('out-of-memory') scopes and races it against device loss. Asynchronous shader or pipeline validation errors now count as failures, not success (issue comment 2). The adapter is checked once at mount: if the adapter is null, the row is hidden and the panel says WEBGPU UNAVAILABLE: HEATMAP AND COMPUTE BENCHMARK OFF.
  • Header: the header shows SYS LOADING, SYS NOMINAL, or SYS DEGRADED, computed by a pure deriveSystemStatus in src/status/systemStatus.js. The status element is role="status" with aria-live="polite", and the list of issues is in its title and in visually hidden text. On narrow screens it stays out of the visual layout (as in Layout breaks on mobile: header text overlaps and panels overflow at 375px #5) but is clipped instead of display: none, so screen readers still announce it. The collapsed "Sensor layers" toggle shows <n> FAILED and its accessible name includes that count.
  • Render device (issue comment 1): RENDER shows Failed if deck reports an error before its device exists, or if MapLibre itself cannot be created. It shows Lost when the initialized device's lost promise resolves while the map is mounted. Both make the header DEGRADED.
  • Basemap: MapLibre onError with no sourceId before load shows BASEMAP UNAVAILABLE / DATA LAYERS STILL SHOWN. If the map could not be created at all, it shows MAP UNAVAILABLE / WEBGL2 REQUIRED instead.

Unchanged: #4 names and popup focus, #5 layout breakpoints, #7 contrast (every new color: rule is in TEXT_PAIRS, and RETRY is at least 24x24 with a 2px focus ring), #8 RENDER from onDeviceInitialized, #11 benchmark, #15 projection.

Plan

docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md, committed at ef231b3 before any code. Revisions during the work, each made in the commit that departed from the plan:

  • AC8: heatmap waiting counts as LOADING only while airports are loading. Otherwise empty airports would leave the header on LOADING forever.
  • The frozen tests live in their own files, and the header markup tests are in src/App.header.test.jsx.
  • After review: NO AIRPORT DATA also shows when airports load with 0 airports (AC4); the adapter is checked at mount (AC4, Risks); map creation failure is handled (AC6, AC7); a late deck error after unmount is ignored (AC6); the file list and Proof name every test; the unsupported wording now matches the code.

Test evidence

Gate on 570c5f0, every command exited 0:

  • npm ci: 0 vulnerabilities
  • npm run lint: clean
  • npm test: 43 files, 391 tests passed (baseline on origin/main was 32 files, 290 tests)
  • npm run build: built; the 500 kB chunk warning was already there
  • npm audit --omit=dev --audit-level=high: 0 vulnerabilities

Frozen defect tests, each committed red before its fix:

  • src/App.status.test.jsx: the issue reproduction. A failed airports or ports load showed no error and the header said SYS NOMINAL.
  • src/hooks/useGPUHeatmap.asyncValidation.test.js: an async validation error was reported as success.
  • src/App.emptyAirports.test.jsx, src/hooks/useGPUHeatmap.adapterProbe.test.js, src/components/MapView.mapCreate.test.jsx, src/components/MapView.lateError.test.jsx: review findings.

Live drive: vite preview with Playwright 1.64.1, headless Chromium, swiftshader WebGPU. The implementer and a separate verifier each drove it:

  • Airports blocked (raw.githubusercontent.com aborted): AIRPORTS showed LOAD FAILED with RETRY, HEATMAP showed NO AIRPORT DATA, and the header read SYS DEGRADED: AIRPORTS FAILED.
  • Retry: with the block removed, RETRY by keyboard (Enter) or mouse moved focus to the layer checkbox, showed LOADING..., then 72,690 FEATURES. The heatmap reached READY and the header SYS NOMINAL. A window marker survived and performance.timeOrigin was unchanged, so the page did not reload.
  • Ports blocked: the same flow, ending at 1,081 FEATURES and NOMINAL.
  • Basemap blocked (basemaps.cartocdn.com aborted): BASEMAP UNAVAILABLE appeared, the data layers still drew, and the header read SYS DEGRADED: BASEMAP FAILED.
  • Heatmap validation error (injected through popErrorScope): COMPUTE FAILED, then Retry Heatmap, COMPUTING..., READY.
  • No adapter, or no navigator.gpu: the note showed and the header listed WEBGPU UNAVAILABLE.
  • WebGL blocked: MAP UNAVAILABLE / WEBGL2 REQUIRED, RENDER Failed.
  • WEBGL_lose_context.loseContext(): RENDER Lost, and the header read SYS DEGRADED: RENDER LOST.
  • Layout at 375x812 (panel expanded), 768x1024 and 1440x900, with an error and RETRY visible: RETRY measured 44x24, nothing overflowed horizontally, and the panel did not overlap the header or the GPU panel. The focus ring was a visible 2px accent outline. At 375 the collapsed toggle read "Sensor layers, 2 failed".
  • Neighboring flows: the feature popup opened, closed with Escape, and returned focus (Layer toggles, stress slider, and feature popup are not keyboard or screen reader accessible #4). The bottom sheet worked at 375 (Layout breaks on mobile: header text overlaps and panels overflow at 375px #5). The RUN benchmark returned a GB/s figure (GPU compute benchmark runs a 64 MB dispatch every second indefinitely, including in hidden tabs #11).

Review findings

First round: three Claude finders (bugs and compliance; security; outside the diff) and two Fable finders (bugs and compliance; edge cases), then delta rounds.

Fixed:

  • A: airports loaded with 0 airports left HEATMAP at AWAITING AIRPORTS forever. Raised by Claude (three finders); Fable noted it.
  • B: a null adapter was only detected after airports were non-empty, so the WebGPU note and WEBGPU UNAVAILABLE could be missing. Raised by Claude and by Fable (both finders).
  • C: when MapLibre could not be created, the page said DATA LAYERS STILL SHOWN and RENDER stayed Detecting.... Raised by Claude.
  • E: a deck error after unmount wrote render failed into the global store. Raised by Claude.
  • F, H, I, J: README and plan wording (layout tree, NO AIRPORT DATA cases, the file list, unsupported wording). Raised by Claude.

Left as nits:

  • D: if a heatmap Retry ends in unsupported (an adapter present at mount but null on retry), the focused row unmounts and focus falls to body. Raised by Claude.
  • The frozen src/App.emptyAirports.test.jsx header comment says "0 rows" where the code means 0 airports. It is left as is because frozen tests are not edited.

Dismissed:

  • G: no sprite-error-then-load test. The plan accepts that risk, and the load-clears-failure path is tested. Raised by Claude.

Verifier: no findings.

Notes:

  • Store health is not reset if MapView remounts, which it never does here.
  • Tile and TileJSON errors carry a sourceId and are ignored by design (AC7).
  • The RUN button still shows with a null adapter. That predates this change.

Docs reconciled

  • README.md: Features (heatmap statuses, new Load states bullet, small-screen header), Requirements (WebGPU missing), project layout (src/status/, store health), Known limitations (airports, basemap, RENDER).
  • CLAUDE.md: no change needed. Its rules still hold, and the two existing eslint-disable comments are the pre-existing ones.
  • ADR: none.

Closes #10

🤖 Generated with Claude Code

https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf

GeoBradDev and others added 25 commits November 7, 2026 21:49
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…m status (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…as success (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…failed or unsupported (#10)

The heatmap compute now pushes validation and out-of-memory error scopes,
pops them after the last readback, and races the readbacks against
device.lost, so an asynchronous shader or pipeline validation error ends in
status error instead of ready. Adds the status model and a stable retry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…the layer panel (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
… error and SYS NOMINAL (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…from real state (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…d keep the narrow header status announced (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…r an empty airports file (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…waiting without airports (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…#10)

The adapter probe for finding B adds a requestAdapter call at mount, so the
compute run count is measured by the device request each run makes. Passes
before and after the probe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…ed without airports (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…as target (#10)

Real MapLibre error events carry the map as target; react-maplibre sends
target: null only when the map cannot be created (finding C). Passes before
and after that fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…ayers are still shown (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…ER Failed (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…nder failed (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…r device (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…E layout (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…ATA README note (#10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
@GeoBradDev
GeoBradDev merged commit 18e2362 into main Nov 8, 2026
1 check passed
@GeoBradDev
GeoBradDev deleted the issue-10-loading-error-degraded-states branch November 8, 2026 04:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

No loading, error, or degraded states: failed data loads leave an empty map and SYS NOMINAL

1 participant